<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>SchemeScript - Interacting with an interpreter</title>
    <link href="schemescript.css" rel="stylesheet" type="text/css">
</head>

<body>

<h1>Interacting with an interpreter</h1>

<h2>The embedded Kawa interpreter</h2>
<p>
	It is possible to interact with the Kawa interpreter embedded in the SchemeScript plugin. Using this 
	interpreter, one can script (though to a limited extent) Eclipse in Scheme. For example, most of the
	functionality in version 1.0.0 has been developed interactively using this interpreter.
</p>

<h3>Kawa Stack trace View</h3>
<p>
    When an error occurs in the interpreted code, the stack trace can be display in 
    the Kawa Stacktrace View:  
</p>
<center><img src="images/stacktrace.JPG"/></center>

<h3>Kawa Scratchpad</h3>
<p>
	The Kawa interpreter can also be used to test custom SWT/JFace controls developed in Kawa Scheme. 
	To do this, call the <code>add-scratchpad-view</code> function with two parameters:
	a symbol for identifying the view, and a function of one argument that will be called
	to create the control in the parent control passed in argument.
</p>	
<p>
	The file <code>examples/circles.scm</code> that can be found in the plugin distribution
	is an example of such a control created in Scheme. Here is the result of loading
	this file:
</p>
<center><img src="images/scratchpad.JPG"/></center>

<h2>Connecting to a remote Scheme interpreter</h2>

<p>
  Many Scheme interpreters can be started in <i>server</i> mode, waiting for another process
  to connect on a specific TCP/IP port number. The remote interpreter interface
  allows SchemeScript to communicate with such interpreters.
</p>

<p>
  The SchemeScript remote interpreter interface is <a href="http://siscweb.sourceforge.net">SISCweb</a>
  ready, i.e. it will connect to port 5156 on <tt>localhost</tt> by default. This can be changed
  using the <a href="prefs.html#remote">preference page</a>.
</p>

<h2>Interacting with an external Scheme interpreter</h2>

<p>
	SchemeScript provides a minimal interface external to Scheme interpreters. 
</p>

<h3>Configuring the interpreter</h3>
<p>
	To configure a Scheme interpreter, open the <a href="prefs.html#interp">External Interpreter</a> preference page.
</p>

<h3>Extracting error locations</h3>
<p>
	When an error occurs in the interpreter, SchemeScript can turn the location
	of the error into an hyperlink (given that it is appropriately <a href="prefs.html#interp">configured</a>). Here is the
	result of an interaction with the MzScheme interpreter:
	<center><img src="images/errorlink.JPG"/></center>
	Clicking on the hyperlink will open the file containing the error and select
	the line containing the error.
</p>

<h2>Launching the interpreter</h2>
<p>
	To launch the interpreter from the Scheme perspective, select the interpreter using
	the "Scheme/Select Interpreter" menu item, and then select the "Scheme/Start Interpreter" 
	menu item or click on the "Start Interpreter" toolbar button. The interpreter will be accessible 
	from the Console View:
</p>
<center><img src="images/console.JPG"/></center>
<p>
	In this example, an external Kawa interpreter is run. 
</p>

<h2>Sending expressions to the interpreter</h2>
<p>
	S-expressions can be sent directly to the interpreter for evaluation using the 
	<b>Eval Expression</b> and <b>Eval toplevel Expression</b> commands from
	the editor (<i> &agrave; la </i> Emacs). See <a href="editing.html#eval">Editing</a>.
</p>
<p>
	For example, suppose that the cursor is located after the closing parenthesis in:
	<center><img src="images/console.JPG"/></center>
	Pressing Ctrl-Enter will send to whole expresssion (the <code>define</code>	form)
	to the interpreter. Also, pressing Ctrl-Shift-Enter will send to the interpreter
	the top-level expression that encloses the cursor position.
</p>
<p>
	The whole editor content can be sent to the interpreter using the <b>Load File in Interpreter</b>
	command, which is bound to the Ctrl-Shift-L key sequence by default.
</p>

<h3>Interrupting an evaluation</h3>
<p>
   <b>Note:</b> This applies only to external interpreters.
</p>
<p>
	If the external interpreter supports interruption using </code>kill -2</code>, follow these steps before
	starting the interpreter:
	<ul>
		<li> Check the "Interpreter saves PID" check box in the "Scheme/External Interpreter" preference page.
		<li> Pass the name of the file where the PID of the Scheme process must be stored to the Scheme interpreter
		     using the <code>{pidfile}</code> variable on the command-line arguments. The Scheme process must then
		     save its PID in the given file. (Most Scheme system allow the evaluation of command-line arguments).
	</ul>
</p>
<p>
	To interrupt an evaluation, simply select the "Scheme/Interrupt Evaluation" menu item or press ALT-F9 in the
	Scheme perspective. You can also click on the corresponding toolbar button.
</p>

<h2>Fast Eval keys</h2>
<p>
	<i>Fast Eval keys</i> are configurable commands that send predefined expressions
	to the interpreter. These expressions are configured in the 
    <a href="prefs.html#fasteval">Fast Eval preference page</a>.
</p>
<p>
	For example, suppose that Fast Eval Key #0 is set to <code>(test)</code>. Every time
	the Fast Eval 0 command is run (by pressing Alt-K 0 by default), the string
	<code>(test)</code> is sent to the interpreter. 
</p>

<hr/>
<p>
	Copyright (C) 2004-2006 <b>Dominique Boucher</b>.
</p>
</body>
</html>